﻿<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>GoJS Buttons -- Northwoods Software</title>
  <!-- Copyright 1998-2021 by Northwoods Software Corporation. -->
  <script src="../release/go.js"></script>
  <script src="goIntro.js"></script>
</head>
<body onload="goIntro()">
<div id="container" class="container-fluid">
<div id="content">

<h1>Buttons</h1>
<p>
For your convenience we have defined several <a>Panel</a>s for common uses.
These include "Button", "TreeExpanderButton", "SubGraphExpanderButton", "PanelExpanderButton", and "ContextMenuButton".
</p>
<p>
These predefined panels can be used as if they were <a>Panel</a>-derived classes in calls to <a>GraphObject,make</a>.
They are implemented as simple visual trees of <a>GraphObject</a>s in <a>Panel</a>s,
with pre-set properties and event handlers.
</p>
<p>
You can see a copy of their definitions in this file:
<a href="../extensions/Buttons.js">Buttons.js</a>.
</p>
<p>
See samples that make use of buttons in the <a href="../samples/index.html#buttons">samples index</a>.
In addition, see the <a href="../extensions/Checkboxes.html">Checkboxes</a> extension for an example of using "CheckBoxButton".
</p>


<h2 id="GeneralButtons">General Buttons</h2>
<p>
The most general kind of predefined <a>Panel</a> is "Button".
</p>
<pre class="lang-js" id="button">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { locationSpot: go.Spot.Center },
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.Panel, "Vertical",
        { margin: 3 },
        $("Button",
          { margin: 2,
            click: incrementCounter },
          $(go.TextBlock, "Click me!")),
        $(go.TextBlock,
          new go.Binding("text", "clickCount",
                         function(c) { return "Clicked " + c + " times."; }))
      )
    );

  function incrementCounter(e, obj) {
    var node = obj.part;
    var data = node.data;
    if (data && typeof(data.clickCount) === "number") {
      node.diagram.model.commit(function(m) {
        m.set(data, "clickCount", data.clickCount + 1);
      }, "clicked");
    }
  }

  diagram.model = new go.GraphLinksModel(
    [ { clickCount: 0 } ]);
</pre>
<script>goCode("button", 600, 150)</script>

<p>
Buttons are just Panels holding a Shape that will surround whatever content you give it.
The border Shape is named "ButtonBorder" so that you can easily set or bind its properties.
</p>
<p>
The event handlers defined by all "Button"s make use of additional properties,
not defined in the API, but that you can see in the definition of "Button":
<a href="../extensions/Buttons.js">Buttons.js</a>.
These properties parameterize the appearance of the button.
</p>
<pre class="lang-js" id="button2">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      { locationSpot: go.Spot.Center },
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.Panel, "Vertical",
        { margin: 3 },
        $("Button",
          {
            margin: 2,
            // set properties on the border Shape of the "Button"
            "ButtonBorder.fill": "fuchsia",
            // set properties on the "Button" itself used by its event handlers
            "_buttonFillOver": "pink",
            click: function(e, button) { alert(button.findObject("ButtonBorder").fill); }
          },
          $(go.TextBlock, "fuchsia button\nwith pink highlight", { margin: 2, textAlign: "center" })
        ),
        $("Button",
          {
            margin: 2,
            // set properties on the border Shape of the "Button"
            "ButtonBorder.figure": "Circle",
            "ButtonBorder.fill": "cyan",
            "ButtonBorder.stroke": "darkcyan",
            "ButtonBorder.strokeWidth": 3,
            // set properties on the "Button" itself used by its event handlers
            "_buttonFillOver": "white",
            "_buttonStrokeOver": "cyan",
            "_buttonFillPressed": "lightgray",
            click: function(e, button) { alert(button.findObject("ButtonBorder").stroke); }
          },
          $(go.TextBlock, "Circular\nbutton", { margin: 2, textAlign: "center" })
        ),
        $("Button",
          {
            margin: 2,
            click: function(e, button) { alert(button.findObject("PIC").source); }
          },
          // the button content can be anything -- it doesn't have to be a TextBlock
          $(go.Picture, "images/50x40.png", { name: "PIC", width: 50, height: 40 })
        ),
        $("Button",
          {
            margin: 2,
            // buttons can be disabled too, by either setting or data binding:
            isEnabled: false,
            click: function(e, button) { alert("won't be alerted"); }
          },
          $(go.TextBlock, "disabled", { stroke: "gray" })
        )
      )
    );

  diagram.model = new go.GraphLinksModel([ { } ]);
</pre>
<script>goCode("button2", 600, 250)</script>


<h2 id="TreeExpanderButtons">TreeExpanderButtons</h2>
<p>
It is common to want to expand and collapse subtrees.
It is easy to let the user control this by adding an instance of the "TreeExpanderButton" to your node template.
The button calls <a>CommandHandler.collapseTree</a> or <a>CommandHandler.expandTree</a>
depending on the value of <a>Node.isTreeExpanded</a>.
The button's icon's <a>Shape.figure</a> changes as the value of
<a>Node.isTreeExpanded</a> changes.
</p>
<pre class="lang-js" id="treeExpanderButton">
  diagram.nodeTemplate =
    $(go.Node, "Spot",
      $(go.Panel, "Auto",
        $(go.Shape, "Rectangle",
          { fill: "gold" }),
        $(go.TextBlock, "Click small button\nto collapse/expand subtree",
          { margin: 5 })
      ),
      $("TreeExpanderButton",
        { alignment: go.Spot.Bottom, alignmentFocus: go.Spot.Top },
        { visible: true })
    );

  diagram.layout = $(go.TreeLayout, { angle: 90 });

  diagram.model = new go.GraphLinksModel(
    [ { key: 1 },
      { key: 2 } ],
    [ { from: 1, to: 2 } ] );
</pre>
<script>goCode("treeExpanderButton", 600, 200)</script>

<p>
A "TreeExpanderButton" is a "Button" that holds a Shape displaying either a "MinusLine" or a "PlusLine"
figure, depending on the value of the <a>Node.isTreeExpanded</a>.
That shape is named "ButtonIcon", so that you can easily set or bind its properties,
in addition to the properties of the "ButtonBorder" and of the "Button" itself.
</p>
<pre class="lang-js" id="treeExpanderButton2">
  diagram.nodeTemplate =
    $(go.Node, "Spot",
      $(go.Panel, "Auto",
        $(go.Shape, "Rectangle",
          { fill: "gold" }),
        $(go.TextBlock, "Click small button\nto collapse/expand subtree",
          { margin: 5 })
      ),
      $("TreeExpanderButton",
        {
          // set the two additional properties used by "TreeExpanderButton"
          // that control the shape depending on the value of Node.isTreeExpanded
          "_treeExpandedFigure": "TriangleUp",
          "_treeCollapsedFigure": "TriangleDown",
          // set properties on the icon within the border
          "ButtonIcon.fill": "darkcyan",
          "ButtonIcon.strokeWidth": 0,
          // set general "Button" properties
          "ButtonBorder.figure": "Circle",
          "ButtonBorder.stroke": "darkcyan",
          "_buttonStrokeOver": "darkcyan"
        },
        { alignment: go.Spot.Bottom, alignmentFocus: go.Spot.Top },
        { visible: true })
    );

  diagram.layout = $(go.TreeLayout, { angle: 90 });

  diagram.model = new go.GraphLinksModel(
    [ { key: 1 },
      { key: 2 } ],
    [ { from: 1, to: 2 } ] );
</pre>
<script>goCode("treeExpanderButton2", 600, 200)</script>


<h2 id="SubGraphExpanderButtons">SubGraphExpanderButtons</h2>
<p>
It is also common to want to expand and collapse groups containing subgraphs.
You can let the user control this by adding an instance of the "SubGraphExpanderButton" to your group template.
The button calls <a>CommandHandler.collapseSubGraph</a> or <a>CommandHandler.expandSubGraph</a>
depending on the value of <a>Group.isSubGraphExpanded</a>.
The button's icon's <a>Shape.figure</a> changes as the value of
<a>Group.isSubGraphExpanded</a> changes.
</p>
<pre class="lang-js" id="subgraphExpanderButton">
  diagram.groupTemplate =
    $(go.Group, "Auto",
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.Panel, "Vertical",
        { margin: 5,
          defaultAlignment: go.Spot.Left },
        $(go.Panel, "Horizontal",
          $("SubGraphExpanderButton",
            { margin: new go.Margin(0, 3, 5, 0) }),
          $(go.TextBlock, "Group")
        ),
        $(go.Placeholder)
      )
    );

  diagram.model = new go.GraphLinksModel(
    [ { key: 0, isGroup: true },
      { key: 1, group: 0 },
      { key: 2, group: 0 },
      { key: 3, group: 0 } ] );
</pre>
<script>goCode("subgraphExpanderButton", 600, 150)</script>

<p>
A "SubGraphExpanderButton" is like a "TreeExpanderButton" in its being a "Button"
with a border Shape surrounding an icon Shape.
That shape is named "ButtonIcon", so that you can easily set or bind its properties,
in addition to the properties of the "ButtonBorder" and of the "Button" itself.
</p>
<pre class="lang-js" id="subgraphExpanderButton2">
  diagram.groupTemplate =
    $(go.Group, "Auto",
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.Panel, "Vertical",
        { margin: 5,
          defaultAlignment: go.Spot.Left },
        $(go.Panel, "Horizontal",
          $("SubGraphExpanderButton",
            {
              // set the two additional properties used by "SubGraphExpanderButton"
              // that control the shape depending on the value of Group.isSubGraphExpanded
              "_subGraphExpandedFigure": "TriangleUp",
              "_subGraphCollapsedFigure": "TriangleDown",
              // set other properties on the button icon
              "ButtonIcon.angle": -45,
              // and properties on the button border or the button itself
              "ButtonBorder.opacity": 0.0
            }),
          $(go.TextBlock, "Group")
        ),
        $(go.Placeholder)
      )
    );

  diagram.model = new go.GraphLinksModel(
    [ { key: 0, isGroup: true },
      { key: 1, group: 0 },
      { key: 2, group: 0 },
      { key: 3, group: 0 } ] );
</pre>
<script>goCode("subgraphExpanderButton2", 600, 150)</script>


<h2 id="PanelExpanderButtons">PanelExpanderButtons</h2>
<p>
It is common to want to expand and collapse a piece of a node,
thereby showing or hiding details that are sometimes not needed.
It is easy to let the user control this by adding an instance of the "PanelExpanderButton" to your node template.
The second argument to <a>GraphObject,make</a> should be a string that names the element in the node whose
<a>GraphObject.visible</a> property you want the button to toggle.
</p>
<pre class="lang-js" id="panelExpanderButton">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape,
        { fill: "gold" }),
      $(go.Panel, "Table",
        { defaultAlignment: go.Spot.Top, defaultColumnSeparatorStroke: "black" },
        $(go.Panel, "Table",
          { column: 0 },
          $(go.TextBlock, "List 1",
            { column: 0, margin: new go.Margin(3, 3, 0, 3),
              font: "bold 12pt sans-serif" }),
          $("PanelExpanderButton", "LIST1",
            { column: 1 }),
          $(go.Panel, "Vertical",
            { name: "LIST1", row: 1, column: 0, columnSpan: 2 },
            new go.Binding("itemArray", "list1"))
        ),
        $(go.Panel, "Table",
          { column: 1 },
          $(go.TextBlock, "List 2",
            { column: 0, margin: new go.Margin(3, 3, 0, 3),
              font: "bold 12pt sans-serif" }),
          $("PanelExpanderButton", "LIST2",
            { column: 1 }),
          $(go.Panel, "Vertical",
            { name: "LIST2", row: 1, column: 0, columnSpan: 2 },
            new go.Binding("itemArray", "list2"))
        )
      )
    );

  diagram.model = new go.GraphLinksModel([
    {
      key: 1,
      list1: [ "one", "two", "three", "four", "five" ],
      list2: [ "first", "second", "third", "fourth" ]
    }
  ]);
</pre>
<script>goCode("panelExpanderButton", 600, 200)</script>

<p>
A "PanelExpanderButton" is like a "TreeExpanderButton" or "SubGraphExpanderButton"
in its being a "Button" with a border Shape surrounding an icon Shape.
However, this panel binds the <a>Shape.geometryString</a> rather than the <a>Shape.figure</a>.
</p>
<pre class="lang-js" id="panelExpanderButton2">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape,
        { fill: "gold" }),
      $(go.Panel, "Table",
        { defaultAlignment: go.Spot.Top, defaultColumnSeparatorStroke: "black" },
        $(go.Panel, "Table",
          { column: 0 },
          $(go.TextBlock, "List 1",
            { column: 0, margin: new go.Margin(3, 3, 0, 3),
              font: "bold 12pt sans-serif" }),
          $("PanelExpanderButton", "LIST1",
            { column: 1,
              // set the two additional properties used by "PanelExpanderButton"
              // that control the shape depending on the value of GraphObject.visible
              // of the object named "LIST1"
              "_buttonExpandedFigure": "M0 0 L10 0",
              "_buttonCollapsedFigure": "M0 5 L10 5 M5 0 L5 10",
              "ButtonIcon.stroke": "blue",
              height: 16
            }),
          $(go.Panel, "Vertical",
            { name: "LIST1", row: 1, column: 0, columnSpan: 2 },
            new go.Binding("itemArray", "list1"))
        ),
        $(go.Panel, "Table",
          { column: 1 },
          $(go.TextBlock, "List 2",
            { column: 0, margin: new go.Margin(3, 3, 0, 3),
              font: "bold 12pt sans-serif" }),
          $("PanelExpanderButton", "LIST2",
            { column: 1,
              // set the two additional properties used by "PanelExpanderButton"
              // that control the shape depending on the value of GraphObject.visible
              // of the object named "LIST1"
              "_buttonExpandedFigure": "F M0 10 L5 0 10 10z",
              "_buttonCollapsedFigure": "F M0 0 L10 0 5 10z",
              "ButtonIcon.strokeWidth": 0,
              "ButtonIcon.fill": "blue"
            }),
          $(go.Panel, "Vertical",
            { name: "LIST2", row: 1, column: 0, columnSpan: 2 },
            new go.Binding("itemArray", "list2"))
        )
      )
    );

  diagram.model = new go.GraphLinksModel([
    {
      key: 1,
      list1: [ "one", "two", "three", "four", "five" ],
      list2: [ "first", "second", "third", "fourth" ]
    }
  ]);
</pre>
<script>goCode("panelExpanderButton2", 600, 200)</script>


<h2 id="ContextMenuButtons">ContextMenuButtons</h2>
<p>
Although you can implement context menus in any way you choose, it is common to use the predefined "ContextMenuButton".
</p>
<pre class="lang-js" id="contextMenuButtons">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.TextBlock, "Use ContextMenu!",
        { margin: 5 })
    );

  diagram.nodeTemplate.contextMenu =
    $("ContextMenu",
      $("ContextMenuButton",
        $(go.TextBlock, "Shift Left"),
        { click: function(e, obj) { shiftNode(obj, -20); } }),
      $("ContextMenuButton",
        $(go.TextBlock, "Shift Right"),
        { click: function(e, obj) { shiftNode(obj, +20); } })
    );

  function shiftNode(obj, dist) {
    var adorn = obj.part;
    var node = adorn.adornedPart;
    node.diagram.commit(function(d) {
      var pos = node.location.copy();
      pos.x += dist;
      node.location = pos;
    }, "Shift");
  }

  diagram.model = new go.GraphLinksModel(
    [ { key: 1 } ] );
</pre>
<script>goCode("contextMenuButtons", 600, 150)</script>
<p>
For an example of defining context menus using HTML, see the <a href="../samples/customContextMenu.html">Custom ContextMenu sample</a>.
</p>

<p>
A "ContextMenuButton" is just a "Button" with a few properties set.
One of those properties is <a>GraphObject.stretch</a>, which is set to
<code>go.GraphObject.Horizontal</code> so that all of the "ContextMenuButton"s
in a "ContextMenu" will be stretch to the same width.
But you can set all of the usual properties on both its "ButtonBorder" Shape
as well as on the button itself.
</p>
<pre class="lang-js" id="contextMenuButtons2">
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape, "Rectangle",
        { fill: "gold" }),
      $(go.TextBlock, "Use ContextMenu!",
        { margin: 5 })
    );

  diagram.nodeTemplate.contextMenu =
    $("ContextMenu",
      $("ContextMenuButton",
        {
          "ButtonBorder.fill": "yellow",
          "_buttonFillOver": "cyan",
          "_buttonFillPressed": "lime"
        },
        $(go.TextBlock, "Shift Left"),
        { click: function(e, obj) { shiftNode(obj, -20); } }
      ),
      $("ContextMenuButton",
        {
          "ButtonBorder.fill": "yellow",
          "_buttonFillOver": "cyan",
          "_buttonFillPressed": "lime"
        },
        $(go.TextBlock, "Shift Right"),
        { click: function(e, obj) { shiftNode(obj, +20); } }
      ),
      $("ContextMenuButton",
        { isEnabled: false },
        $(go.TextBlock, "Shift Right", { stroke: "gray" }),
        { click: function(e, obj) { alert("won't be alerted"); } }
      )
    );

  function shiftNode(obj, dist) {
    var adorn = obj.part;
    var node = adorn.adornedPart;
    node.diagram.commit(function(d) {
      var pos = node.location.copy();
      pos.x += dist;
      node.location = pos;
    }, "Shift");
  }

  diagram.model = new go.GraphLinksModel(
    [ { key: 1 } ] );
</pre>
<script>goCode("contextMenuButtons2", 600, 150)</script>

<p>
See also the fancier round context menu implemented in
<a href="../samples/radialAdornment.html">Radial Context Menu</a>.
</p>

<h2 id="ButtonDefinitions">Button Definitions</h2>
<p>
The implementation of all predefined buttons is provided in <a href="../extensions/Buttons.js">Buttons.js</a>
in the Extensions directory.
You may wish to copy and adapt these definitions when creating your own buttons.
</p>
<p>
Those definitions might not be an up-to-date description
of the actual standard button implementations that are in <b>GoJS</b> and used by <a>GraphObject,make</a>.
</p>
<p>
Note that the definitions of those buttons makes use of the <a>GraphObject.defineBuilder</a> static function.
That extends the behavior of <a>GraphObject,make</a> to allow the creation of fairly complex visual trees by name with optional arguments.
You can find the definitions of various kinds of controls throughout the samples and extensions, such as at:
<ul>
  <li><a href="../extensions/Buttons.js">Buttons.js</a></li>
  <li><a href="../extensions/HyperlinkText.js">HyperlinkText.js</a></li>
  <li><a href="../extensions/ScrollingTable.js">ScrollingTable.js</a></li>
  <li><a href="../extensions/ScrollingTable.js">AutoRepeatButton</a></li>
</ul>
</p>

</div>
</div>
</body>
</html>
